Keychain#

The Keychain API allowing secure storage, retrieval, and management of sensitive data. This guide explains the methods and options available to use the Keychain API effectively.

Module: Keychain#

Methods#

Keychain.set(key: string, value: string, options?: KeychainOptions): void#

Description
Encrypts and saves the specified key with the given value. If the key already exists in the Keychain, its associated value will be updated.

Parameters

• key: A unique identifier for the value to store (string)
• value: The value to securely store (string)
• options (optional): Configuration options for the Keychain item

Usage Example

1// Store a user token with accessibility options
2Keychain.set(
3  'userToken',
4  'abc123',
5  {
6    accessibility: 'unlocked',
7    synchronizable: true
8  }
9)

Keychain.get(key: string, options?: KeychainOptions): string | null#

Description
Decrypts and retrieves the value associated with the specified key. Returns null if the key does not exist.

Parameters

• key: A unique identifier for the value to retrieve (string)
• options (optional): Configuration options for accessing the Keychain item

Returns

• The stored value (string) or null if the key is not found.

Usage Example

1// Retrieve a stored token
2const token = Keychain.get(
3  'userToken',
4  {
5    accessibility: 'unlocked'
6  }
7)
8if (token) {
9  console.log(`Retrieved token: ${token}`)
10} else {
11  console.log('No token found')
12}

Keychain.remove(key: string, options?: KeychainOptions): void#

Description
Deletes the value associated with the specified key. If the key does not exist, this method does nothing.

Parameters

• key: A unique identifier for the value to delete (string)
• options (optional): Configuration options for the Keychain item

Usage Example

1// Remove a stored token
2Keychain.remove('userToken')
3console.log('Token deleted')

Keychain.contains(key: string, options?: KeychainOptions): boolean#

Description
Checks if the Keychain contains a value for the specified key.

Parameters

• key: A unique identifier for the value to check (string)
• options (optional): Configuration options for the Keychain item

Returns

• true if the Keychain contains the key, otherwise false.

Usage Example

1// Check if a key exists in the Keychain
2if (Keychain.contains('userToken')) {
3  console.log('Token exists')
4} else {
5  console.log('Token does not exist')
6}

Types#

KeychainOptions#

Configuration options for Keychain items.

KeychainAccessibility#

Specifies when the Keychain item is accessible.
Available values:

• passcode: Data is accessible only when the device is unlocked. Requires a passcode and does not migrate to new devices.
• unlocked: Data is accessible while the device is unlocked by the user.
• unlocked_this_device: Same as unlocked, but does not migrate to new devices.
• first_unlock: Data is accessible after the first unlock following a device restart.
• first_unlock_this_device: Same as first_unlock, but does not migrate to new devices.

Common Use Cases#

Storing and Retrieving User Tokens#

1// Store a user token
2Keychain.set(
3  'authToken',
4  'secureToken',
5  {
6    accessibility: 'unlocked',
7    synchronizable: true
8  }
9)
10
11// Retrieve the token
12const token = Keychain.get(
13  'authToken',
14  {
15    accessibility: 'unlocked',
16    synchronizable: true
17  }
18)
19console.log(token ? `Token: ${token}` : 'No token found')

Securely Storing Sensitive Data#

1// Save sensitive credentials
2Keychain.set('username', 'user123')
3Keychain.set('password', 'password123', { accessibility: 'first_unlock' })
4
5// Retrieve credentials
6const username = Keychain.get('username')
7const password = Keychain.get('password', { accessibility: 'first_unlock' })
8if (username && password) {
9  console.log(`Welcome, ${username}`)
10} else {
11  console.log('Credentials not found')
12}

Removing Secure Data on Logout#

1// Clear user data
2Keychain.remove('authToken')
3Keychain.remove('username')
4Keychain.remove('password')
5console.log('User data cleared')